<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Programming in Lua : 23</title>
<link rel="stylesheet" type="text/css" href="pil.css">
</head>
<body>
<p class="warning">
<A HREF="contents.html"><IMG TITLE="Programming in Lua (first edition)" SRC="capa.jpg" ALT="" ALIGN="left"></A>This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.<BR>The third edition targets Lua 5.2 and is available at <A HREF="http://www.amazon.com/exec/obidos/ASIN/859037985X/theprogrammil3-20">Amazon</A> and other bookstores.<BR>By buying the book, you also help to <A HREF="../donations.html">support the Lua project</A>.
</p>
<table width="100%" class="nav">
<tr>
<td width="10%" align="left"><a href="22.2.html"><img border="0" src="left.png" alt="Previous"></a></td>
<td width="80%" align="center"><a href="contents.html"><font face="Helvetica,Arial,sanserif">
<font color="gray">Programming in </font><font color="blue"> Lua</font>
</font></a></td>
<td width="10%" align="right"><a href="23.1.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
<tr>
<td width="10%" align="left"></td>
<td width="80%" align="center"><a href="contents.html#P3">Part III. The Standard Libraries</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="contents.html#23">Chapter 23. The Debug Library</a></td>
<td width="10%" align="right"></td></tr>
</table>
<hr/>
<a name="debuglib"><h1>23 &ndash; The Debug Library</h1></a>

<p>The debug library does not give you a debugger for Lua,
but it offers all the primitives that you need
for writing a debugger for Lua.
For performance reasons,
the official interface to these primitives is through the C API.
The debug library in Lua is a way to access these functions
directly within Lua code.
This library declares all its functions inside
the <code>debug</code> table.

<p>Unlike the other libraries,
you should use the debug library with parsimony.
First, some of its functionality is not
exactly famous for performance.
Second, it breaks some sacred truths of the language,
such as that you cannot access a local variable from outside
the function that created it.
Frequently, you may not want to open this
library in your final version of a product,
or else you may want to erase it:
<pre>
    debug = nil
</pre>

<p>The debug library comprises two kinds of functions:
<em>introspective</em> functions and <em>hooks</em>.
Introspective functions allow us to inspect several
aspects of the running program,
such as its stack of active functions,
current line of execution,
and values and names of local variables.
Hooks allow you to trace the execution of a program.

<p>An important concept in the debug
library is the <em>stack level</em>.
A stack level is a number that refers to a particular
function that is active at that moment,
that is, it has been called and has not returned yet.
The function calling the debug library has level 1,
the function that called it has level 2,
and so on.

<hr/>
<table width="100%" class="nav">
<tr valign="top">
<td width="90%" align="left">
<small>
  Copyright &copy; 2003&ndash;2004 Roberto Ierusalimschy.  All rights reserved.
</small>
</td>
<td width="10%" align="right"><a href="23.1.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
</table>


</body></html>

